docs: correct payment and fee semantics

docs/DATA-FOUNDATION-SPEC.md

@@ -75,6 +75,7 @@ erDiagram
       bigint merchant_id FK
       bigint terminal_id FK
       bigint amount
+      bigint fee_amount_rial
       text session_status
       timestamptz created_at
       bigint import_run_id FK
@@ -89,7 +90,6 @@ erDiagram
       text issuer_bank_code
       text payer_card_key
       text verify_type
-      bigint adjusted_fee
       int init_time_ms
       int verify_time_ms
       timestamptz try_created_at
@@ -184,6 +184,7 @@ This contract applies only to the one-time challenge-data bootstrap and explicit
 - Daily, weekly, Jalali-month, and Persian-season analytics reconcile to deterministic source queries for additive metrics.
 - Rates are recomputed from their numerator and denominator over the requested period rather than averaged from daily percentages.
 - Non-additive metrics such as unique payer-token counts are never produced by summing daily distinct counts.
+- Source `adjusted_fee` is normalized once per session as `fee_amount_rial`; retry attempts never multiply fee totals.
 - First access idempotently creates/returns one run, starts all four core analytics sections in bounded parallel, and delivers each through authenticated SSE as soon as it is ready.
 - A second equivalent request reads current 30-day Redis entries without repeating source-fact aggregation.
 - Inserting a related payment fact advances only the affected merchant revision and any affected cohort revision; the next relevant request recomputes once and publishes atomically.
@@ -218,6 +219,6 @@ Resolved: holiday and named-event reporting are removed from scope. MVP reportin
 
 Resolved: reporting weeks follow the Iranian week: Saturday through Friday in `Asia/Tehran`, represented as half-open API/database ranges. See ADR 0012.
 
-Resolved: only source session status `Verified` is a definitely successful payment. Keep `Paid` separate until an authoritative ZarinPal definition changes the metric catalogue. See `METRIC-CATALOGUE.md`.
+Resolved: authoritative ZarinPal lifecycle guidance defines both `Paid` and `Verified` as successful bank payments. `Paid` means funds were deducted but merchant verification is incomplete; `Verified` is finalized. Success/paid-volume/recovery metrics include both while verification metrics keep them distinct. Source `adjusted_fee` is treated as the real merchant fee, normalized once per session, and shown in Rial. See ADR 0013 and `METRIC-CATALOGUE.md`.
 
 No broad architecture approval gates remain for this capability. Physical columns, exact SSE event schemas, retryable-error classification, analytics-section response contracts, observability targets, and migration details still require acceptance in the implementation-ready specs.