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/mv/membership_fees/cycle_generator.ex

@@ -371,19 +371,20 @@ defmodule Mv.MembershipFees.CycleGenerator do
       end)
 
     {successes, errors} = Enum.split_with(results, &match?({:ok, _, _}, &1))
-    successful_cycles = Enum.map(successes, fn {:ok, cycle, _notifications} -> cycle end)
 
     all_notifications =
       Enum.flat_map(successes, fn {:ok, _cycle, notifications} -> notifications end)
 
     if Enum.empty?(errors) do
+      successful_cycles = Enum.map(successes, fn {:ok, cycle, _notifications} -> cycle end)
       # Return cycles and notifications to be sent after transaction commits
       {:ok, successful_cycles, all_notifications}
     else
       Logger.warning("Some cycles failed to create: #{inspect(errors)}")
-      # Return partial failure with both successful and failed cycles
-      # This allows callers to decide how to handle partial failures
-      {:error, {:partial_failure, successful_cycles, errors}}
+      # Return partial failure with errors
+      # Note: When this error occurs, the transaction will be rolled back,
+      # so no cycles were actually persisted in the database
+      {:error, {:partial_failure, errors}}
     end
   end
 end