Update Divorce architecture map with fixed business rules

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

docs/architecture-maps/Divorce.md

 # Divorce Module — Architecture Map
 
-> **Last updated:** 2026-06-10
+> **Last updated:** 2026-06-13 (fixed eligibility date, child transfer, rule correction, suggested percentage)
 > **Status:** Living document — incrementally updated as new information is discovered
 
 ---
@@ -117,17 +117,21 @@ board_review → board_approved → fee_paid → completed
    - Upload divorce certificate (REQUIRED — PDF/JPEG/PNG, max 5MB)
    - Validate eligibility via DivorceFeeCalculator::calculate():
      a. Check 1-year window from divorce_date (DIVORCE_REQUEST_WINDOW rule)
-     b. Check 5-year minimum membership (DIVORCE_MIN_MEMBERSHIP_YEARS rule)
-     c. Waived if children exist (waived_if_children flag)
+     b. Check 5-year minimum from SPOUSE's join_date (DIVORCE_MIN_MEMBERSHIP_YEARS rule)
+     c. Waived if children exist on membership (waived_if_children flag)
    - Determine case_type: 'same_form' (joined same day) or 'joined_after'
+   - Calculate suggested percentage based on spouse_order (50% first / 75% second)
    - Create DivorceCase (status='board_review')
    - Dispatch: divorce.submitted
 
 3. POST /divorce/{id}/board-approve
    - Board enters: fee_percentage, board_decision_number, board_decision_date, notes
+   - Board selects children to transfer (checkboxes, fees calculated by age bracket)
    - Calculate fees:
      Fee = (fee_percentage / 100) × membership_value
-     Total = Fee + form_fee (570) + annual_subscription (222 + 35 = 257)
+     ChildFees = sum of (child_percentage × membership_value) for each selected child
+     Total = Fee + form_fee (570) + annual_subscription (257) + ChildFees
+   - Save children_assignment_json with child details (id, name, age, percentage, fee)
    - Status → 'board_approved'
    - Auto-send payment request to Cashier queue
    - Dispatch: divorce.board_approved
@@ -155,7 +159,8 @@ board_review → board_approved → fee_paid → completed
         - original_membership_number = member's number
      c. Assign NEW membership number via MemberNumberGenerator::assign()
      d. Archive spouse record (status='divorced', is_archived=1)
-     e. Update case: spouse_new_member_id, spouse_new_membership_number, original refs
+     e. Transfer children: move selected children (from children_assignment_json) to new member_id
+     f. Update case: spouse_new_member_id, spouse_new_membership_number, original refs
      f. Record number chain via ArchiveService
      g. Status → 'completed'
    - Dispatch: divorce.completed
@@ -176,11 +181,20 @@ Case Type:
 Fee Components:
   - Form Fee: FORM_TRANSFER_FEE rule OR SVC_ADDITION_FORM (default 570 EGP)
   - Annual Subscription: SVC_ANNUAL_CHILD rate + DEVELOPMENT_FEE (default 222 + 35 = 257 EGP)
-  - Percentage Fee: SET BY BOARD (not calculated automatically)
-    Typical: same_form = 10%, joined_after = 50% (from TransferEligibility reference)
-    BUT board can set ANY percentage
-
-Total = (percentage × membership_value) + form_fee + annual_subscription
+  - Percentage Fee: SET BY BOARD (system suggests based on spouse_order):
+    - same_form (joined together) → suggested 10%
+    - joined_after, spouse_order=1 (first spouse) → suggested 50%
+    - joined_after, spouse_order=2 (second spouse) → suggested 75%
+    Board can override with ANY percentage
+  - Children Transfer Fees (age-based, per bylaws):
+    - Under 12: 5% of membership_value (DIVORCE_CHILD_UNDER_12)
+    - 12 to <16: 20% (DIVORCE_CHILD_12_TO_16)
+    - 16 to <18: 25% (DIVORCE_CHILD_16_TO_18)
+    - 18+: 30% (DIVORCE_CHILD_OVER_18)
+
+Total = (percentage × membership_value) + form_fee + annual_subscription + children_fees
+
+Eligibility 5-year check uses SPOUSE's join_date (not member's created_at).
 ```
 
 ---
@@ -193,7 +207,7 @@ Total = (percentage × membership_value) + form_fee + annual_subscription
 | `divorce.board_approved` | `{case_id, fee_percentage}` | DivorceController::boardApprove |
 | `divorce.rejected` | `{case_id}` | DivorceController::boardReject |
 | `divorce.fee_paid` | `{case_id, payment_id}` | DivorceController::pay |
-| `divorce.completed` | `{case_id, new_member_id, new_number}` | DivorceController::complete |
+| `divorce.completed` | `{case_id, new_member_id, new_number, children_transferred}` | DivorceController::complete |
 
 ---