docs/membership-fee-architecture.md

@@ -282,8 +282,14 @@ lib/
 **Implementation Pattern:**
 
 - Use Ash change module to validate
-- Use after_action hook to trigger regeneration
-- Use transaction to ensure atomicity
+- Use after_action hook to trigger regeneration synchronously
+- Regeneration runs in the same transaction as the member update to ensure atomicity
+- CycleGenerator uses advisory locks and transactions internally to prevent race conditions
+
+**Validation Behavior:**
+
+- Fail-closed: If membership fee types cannot be loaded during validation, the change is rejected with a validation error
+- Nil assignment prevention: Attempts to set membership_fee_type_id to nil are rejected when a current type exists
 
 ---
 
@@ -417,7 +423,7 @@ lib/
 **AC-TC-3:** On allowed change: future unpaid cycles regenerated  
 **AC-TC-4:** On allowed change: paid/suspended cycles unchanged  
 **AC-TC-5:** On allowed change: amount updated to new type's amount  
-**AC-TC-6:** Change is atomic (transaction)
+**AC-TC-6:** Change is atomic (transaction) - ✅ Implemented: Regeneration runs synchronously in the same transaction as the member update
 
 ### Settings