add some comments

lib/accounts/user.ex

@@ -60,14 +60,33 @@ defmodule Mv.Accounts.User do
   end
 
   actions do
+    # Default actions kept for framework/tooling integration:
+    # - :create -> Used by AshAdmin's generated "Create" UI and by generic
+    #              AshPhoenix helpers that assume a default create action.
+    #              It does NOT manage the :member relationship. For admin
+    #              flows that may link an existing member, use :create_user.
+    # - :read   -> Standard read used across the app and by admin tooling.
+    # - :destroy-> Standard delete used by admin tooling and maintenance tasks.
     defaults [:read, :create, :destroy]
 
+    # Primary generic update action:
+    # - Selected by AshAdmin's generated "Edit" UI and generic AshPhoenix
+    #   helpers that assume a default update action.
+    # - Intended for simple attribute updates (e.g., :email) and scenarios
+    #   that do NOT need to manage the :member relationship.
+    # - For linking/unlinking a member (and the related validations), prefer
+    #   the specialized :update_user action below.
     update :update do
       primary? true
+
+      # Required because custom validation functions (email validation, member relationship validation)
+      # cannot be executed atomically. These validations need to query the database and perform
+      # complex checks that are not supported in atomic operations.
       require_atomic? false
     end
 
     create :create_user do
+      description "Creates a new user with optional member relationship. The member relationship is managed through the :member argument."
       # Only accept email directly - member_id is NOT in accept list
       # This prevents direct foreign key manipulation, forcing use of manage_relationship
       accept [:email]
@@ -89,12 +108,16 @@ defmodule Mv.Accounts.User do
     end
 
     update :update_user do
+      description "Updates a user and manages the optional member relationship. To change an existing member link, first remove it (set member to nil), then add the new one."
       # Only accept email directly - member_id is NOT in accept list
       # This prevents direct foreign key manipulation, forcing use of manage_relationship
       accept [:email]
       # Allow member to be passed as argument for relationship management
       argument :member, :map, allow_nil?: true
-      # Required because custom validation function cannot be done atomically
+
+      # Required because custom validation functions (email validation, member relationship validation)
+      # cannot be executed atomically. These validations need to query the database and perform
+      # complex checks that are not supported in atomic operations.
       require_atomic? false
 
       # Manage the member relationship during user update