docs: correct payment and fee semantics

docs/METRIC-CATALOGUE.md

@@ -1,37 +1,89 @@
 # Analytics Metric Catalogue
 
-- Status: Draft — definitions are approved individually
-- Version: 0.1.0
+- Status: Draft — listed definitions approved; remaining peer weighting is open
+- Version: 0.2.0
 - Last updated: 2026-08-20
 
-Every merchant-facing number must identify its grain, formula, source fields, filters, time basis, unit, missing-data behavior, trace path, and definition version.
+Every merchant-facing number identifies its grain, formula, source fields, filters, Tehran-local period, unit, missing-data behavior, trace path, and definition version.
 
-## Confirmed successful sessions
+## Bank-paid sessions
 
-- Canonical id: `confirmed_successful_sessions`
+- Canonical id: `bank_paid_sessions`
 - Grain: distinct payment session
-- Formula: count payment sessions where source `session_status = 'Verified'`
+- Formula: count sessions where `session_status IN ('Paid', 'Verified')`
+- Meaning: the buyer completed the bank payment and funds were deducted
 - Unit: sessions
-- Time attribution: session `created_at`, converted to `Asia/Tehran` local reporting date
-- Missing behavior: `session_status` is required; unknown values are not counted and trigger quality evidence
-- Traceability: drill down to eligible session identifiers and their attempt histories within the authenticated merchant
-- Approved decision: `Paid` is not included; it remains a separate state until ZarinPal provides an authoritative definition
+- Time attribution: session `created_at` in `Asia/Tehran`
+- Traceability: merchant-scoped session identifiers and attempt histories
 
-## Paid but not confirmed as verified
+## Payment success rate
 
-- Canonical id: `paid_unverified_sessions`
-- Grain: distinct payment session
-- Formula: count payment sessions where source `session_status = 'Paid'`
+- Canonical id: `payment_success_rate`
+- Numerator: `bank_paid_sessions`
+- Denominator: sessions where `session_status IN ('Paid', 'Verified', 'Failed', 'Reversed')`
+- Formula: numerator / denominator; undefined when denominator is zero
+- Unknown statuses: excluded from both sides and disclosed as coverage/quality evidence until classified
+- Unit: percentage
+
+## Verified sessions
+
+- Canonical id: `verified_sessions`
+- Formula: count sessions where `session_status = 'Verified'`
+- Meaning: bank payment and merchant verification are complete; the payment is finalized
 - Unit: sessions
-- Presentation: separate operational state; never label as confirmed success or failure
-- Traceability: same merchant-scoped session/attempt drill-down
 
-## Open definitions
+## Unverified paid sessions
+
+- Canonical id: `unverified_paid_sessions`
+- Formula: count sessions where `session_status = 'Paid'`
+- Meaning: bank payment succeeded and funds were deducted, but merchant verification is incomplete
+- Presentation: actionable verification gap; never label as failure
+- Unit: sessions
+
+## Verification completion rate
+
+- Canonical id: `verification_completion_rate`
+- Formula: `verified_sessions / bank_paid_sessions`; undefined when no bank-paid sessions exist
+- Unit: percentage
+
+## Paid volume
+
+- Canonical id: `bank_paid_amount_rial`
+- Formula: sum session `amount` once where `session_status IN ('Paid', 'Verified')`
+- Unit: Rial
+- Subsets: `verified_amount_rial` uses `Verified`; `unverified_paid_amount_rial` uses `Paid`
+
+## Retried sessions and eventual payment
+
+- `retried_sessions`: count sessions containing more than one payment attempt
+- `eventually_paid_after_retry_sessions`: count retried sessions whose final session status is `Paid` or `Verified` and which contain a lower-`try_seq` attempt whose status is neither `Paid` nor `Verified`
+- `retry_recovery_rate`: `eventually_paid_after_retry_sessions / retried_sessions`; undefined when no retried sessions exist
+- Grain/unit: distinct sessions
+- Traceability: ordered merchant-scoped attempt history; never depend on CSV row order
+
+## Processing time
+
+- Report median (p50) and p95 separately for `init_time_ms` and `verify_time_ms`
+- Include only non-null values for the relevant field
+- Always show contributing sample count and coverage percentage
+- Do not replace missing timing with zero
+- Unit: milliseconds, with human-readable seconds allowed as an additional presentation
+
+## Merchant fee
+
+- Canonical field: `fee_amount_rial`, sourced from CSV `adjusted_fee` and stored once per session
+- `paid_fee_amount_rial`: sum session fee once where `session_status IN ('Paid', 'Verified')`
+- `paid_fee_rate`: `paid_fee_amount_rial / bank_paid_amount_rial`; undefined when paid amount is zero
+- Meaning/presentation: real merchant fee in Rial; do not label it obfuscated or relative-only in the product
+- Retry rule: never sum the repeated source value per attempt
+
+## Common behavior
+
+- Rates are recomputed from summed numerator/denominator components for every selected day, Saturday–Friday week, Jalali month, and Persian season.
+- Zero, undefined, missing, suppressed peer value, and calculation failure remain distinct states.
+- `Paid` and `Verified` are both bank-payment successes, but only `Verified` is finalized.
+- `Reversed` is not in the success numerator; display it separately when non-zero.
+
+## Open definition
 
-- Success-rate denominator and treatment of `Failed`/`Reversed`/`Paid`
-- Amount metric inclusion by session status
-- Retry and recovery definitions
-- Timing percentile definitions and missing coverage
-- Fee-ratio terminology for obfuscated `adjusted_fee`
 - Merchant-weighted versus transaction-weighted peer comparisons
-