Add deterministic gross-margin scenario calculation

[unes07]

Problem

Fertilizer cost alone does not show whether a crop scenario is economically attractive. A transparent deterministic calculation is required before any prediction is introduced.

Status: Blocked

Blocked by:

• Add price-aware fertilizer product optimization #4
• Publish a versioned fertilizer product catalog for Morocco turba-data#1
• Define and validate fertilizer price observation records turba-data#2
• Build reproducible fertilizer-price ingestion and normalization turba-data#3
• Publish a farm-gate crop-price dataset for supported crops turba-data#4
• Add dataset cards, checksums, semantic versions, and automated validation turba-data#7

Implementation must not start until product, observed-price, crop-price, and optimizer contracts are published.

Inputs

• Field area, expected yield, crop price, and selected fertilizer plan
• Seed, irrigation, labor, fuel, machinery, transport, and other supplied variable costs
• Source, date, freshness, currency, and unit metadata for every price

Outputs

• Revenue and variable cost per hectare and for the full field
• Fertilizer-cost contribution
• Gross margin per hectare and total
• Break-even crop price and yield
• Low, base, and high price/yield scenarios
• Complete source and freshness metadata

Acceptance criteria

• Use transparent arithmetic with no trained model.
• Support observed or user-supplied prices without requiring forecasts.
• Validate area, yield, currency, mass, and price units before calculation.
• Handle negative margins, missing costs, stale prices, mixed units, and zero-area inputs explicitly.
• Preserve scenario inputs and intermediate calculations for auditability.
• Call the result gross margin, not net profit, unless fixed, financing, tax, and capital costs are supplied.
• Preserve results and metadata through Python, JSON, CSV, and batch workflows.