refactor: improve cycle generation code quality and documentation

- Remove Process.sleep calls from integration tests (tests run synchronously in SQL sandbox)
- Improve error handling: membership_fee_type_not_found now returns changeset error instead of just logging
- Clarify partial_failure documentation: successful_cycles are not persisted on rollback
- Update documentation: joined_at → join_date, left_at → exit_date
- Document PostgreSQL advisory locks per member (not whole table lock)
- Document gap handling: explicitly deleted cycles are not recreated

lib/membership_fees/changes/set_membership_fee_start_date.ex

@@ -64,13 +64,26 @@ defmodule Mv.MembershipFees.Changes.SetMembershipFeeStartDate do
       start_date = calculate_start_date(join_date, interval, include_joining_cycle)
       Ash.Changeset.force_change_attribute(changeset, :membership_fee_start_date, start_date)
     else
-      {:error, reason} ->
-        # Log warning for debugging purposes, but don't fail the action
-        # Missing join_date or membership_fee_type_id is expected for partial creates
-        unless reason in [:join_date_not_set, :membership_fee_type_not_set] do
-          Logger.warning("Could not auto-set membership_fee_start_date: #{inspect(reason)}")
-        end
+      {:error, :join_date_not_set} ->
+        # Missing join_date is expected for partial creates
+        changeset
 
+      {:error, :membership_fee_type_not_set} ->
+        # Missing membership_fee_type_id is expected for partial creates
+        changeset
+
+      {:error, :membership_fee_type_not_found} ->
+        # This is a data integrity error - membership_fee_type_id references non-existent type
+        # Return changeset error to fail the action
+        Ash.Changeset.add_error(
+          changeset,
+          field: :membership_fee_type_id,
+          message: "not found"
+        )
+
+      {:error, reason} ->
+        # Log warning for other unexpected errors
+        Logger.warning("Could not auto-set membership_fee_start_date: #{inspect(reason)}")
         changeset
     end
   end