refactor and docs

lib/accounts/user.ex

@@ -228,6 +228,7 @@ defmodule Mv.Accounts.User do
       argument :user_info, :map, allow_nil?: false
       argument :oauth_tokens, :map, allow_nil?: false
       upsert? true
+      # Upsert based on oidc_id (primary match for existing OIDC users)
       upsert_identity :unique_oidc_id
 
       validate &__MODULE__.validate_oidc_id_present/2
@@ -242,8 +243,10 @@ defmodule Mv.Accounts.User do
         |> Ash.Changeset.change_attribute(:oidc_id, user_info["sub"] || user_info["id"])
       end
 
-      # Check for email collisions with existing password-only accounts
+      # Check for email collisions with existing accounts
       # This validation must run AFTER email and oidc_id are set above
+      # - Raises PasswordVerificationRequired for password-protected OR passwordless users
+      # - The LinkOidcAccountLive will auto-link passwordless users without password prompt
       validate Mv.Accounts.User.Validations.OidcEmailCollision
 
       # Sync user email to member when linking (User → Member)