feat: insurance & medical billing system (6 phases)

Multi-tenant insurance contracts, service coverage, versioned tariffs,
invoice calculation, and insurance claims with debt reporting.

- TenantInsurance: per-tenant insurance contracts (coverage/franchise/ceiling,
  versioning, soft-deactivate) + active guard
- ServiceItem.insuranceCovered + TenantServiceCoverage per-service overrides
- Tariff: versioned yearly tariffs with fallback to ServiceItem price
- Billing domain: Money/ShareBreakdown VOs, BillingCalculator (unit-tested),
  Invoice/InvoiceItem aggregate, InvoiceService.createFromSession
- Claim/ClaimItem with state machine (pending->submitted->approved/rejected->paid),
  ClaimService, insurance-debt report
- ClaimSubmitterInterface + ManualClaimSubmitter (future insurance API ready)
- Admin UI: insurance-pricing page, claims page, service tariff modal,
  service insurance toggle; routes + sidebar entries
- Architecture doc + billing/insurance/clinic-services API docs

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/api/clinic-services.md

@@ -111,7 +111,9 @@
   "section_uuid": "...",
   "name": "رادیوگرافی مستقیم",
   "price_rials": 500000,
-  "staff_uuid": "..."
+  "staff_uuid": "...",
+  "insurance_covered": true,
+  "insurance_price_rials": 200000
 }
 ```
 
@@ -121,8 +123,10 @@
 | name | string | ✅ |
 | price_rials | integer | ❌ (پیش‌فرض 0) |
 | staff_uuid | UUID | ❌ |
+| insurance_covered | boolean | ❌ (پیش‌فرض false) — آیا خدمت شامل بیمه می‌شود |
+| insurance_price_rials | integer\|null | ❌ — سهم/قیمت بیمار با بیمه |
 
-**Response 201:** ServiceItem object
+**Response 201:** ServiceItem object (شامل `insurance_covered` و `insurance_price_rials`)
 
 ---
 
@@ -135,7 +139,9 @@
   "name": "رادیوگرافی دیجیتال",
   "price_rials": 600000,
   "staff_uuid": null,
-  "active": false
+  "active": false,
+  "insurance_covered": true,
+  "insurance_price_rials": 250000
 }
 ```
 
@@ -160,3 +166,46 @@
 | ERR_SUBSCRIPTION_REQUIRED | 403 | نیاز به پنل Basic+ |
 | ERR_SERVICE_NOT_FOUND | 404 | سرویس یافت نشد |
 | ERR_SERVICE_ITEM_IN_USE | 409 | سرویس در پرونده بیمار استفاده شده |
+
+---
+
+## تعرفه‌ی نسخه‌دار سالانه (Tariff) — فاز ۳ سیستم صورتحساب
+
+هر خدمت می‌تواند برای هر سال شمسی یک تعرفه داشته باشد. اگر تعرفه‌ی سالی ثبت نشود، به `price_rials` خود خدمت fallback می‌شود (`TariffService::resolvePrice`). سال جاری شمسی سمت سرور با `IntlDateFormatter` (تقویم persian) محاسبه می‌شود.
+
+### GET /api/v1/service-items/{uuid}/tariffs
+
+لیست تعرفه‌های یک خدمت + قیمت پیش‌فرض + سال جاری.
+
+**Permission:** `IS_AUTHENTICATED_FULLY` (مالک خدمت)
+
+```json
+{
+  "success": true,
+  "data": {
+    "current_year": 1405,
+    "default_price_rials": 500000,
+    "data": [
+      { "uuid": "…", "service_item_id": 12, "year": 1405, "price_rials": 600000, "is_active": true },
+      { "uuid": "…", "service_item_id": 12, "year": 1404, "price_rials": 500000, "is_active": true }
+    ]
+  }
+}
+```
+
+### PUT /api/v1/service-items/{uuid}/tariffs/{year}
+
+ثبت/به‌روزرسانی تعرفه‌ی یک سال (upsert). `year` بین ۱۳۹۰ تا ۱۵۰۰.
+
+**Body:**
+```json
+{ "price_rials": 600000 }
+```
+
+**Response 200:** `{ success, data: { …tariff } }`
+
+**Errors:**
+| Code | HTTP | توضیح |
+|------|------|-------|
+| ERR_SERVICE_NOT_FOUND | 404 | سرویس یافت نشد |
+| ERR_VALIDATION_001 | 422 | سال نامعتبر |