Document user IDs for users with emails

[arielshaqed]

I approved #3220 to allow us to move forward on this feature. However I continue not to understand what goes into a "user ID" field of a user defined with an email. As such, it is only a matter of time before I or someone else get confused and introduce a usability or a security bug.

Specifically, the best comment about what goes in this field is this:

the unique identifier for a user was the username or display name (sometimes referred to as user id as well). In the invite user process all we know about the new user is his email. As such we don't have a better uniquely identify the user only by the given email. In order to retain it's uniqueness, we must set it all to lowercase to avoid having the same email twice in the system with different caps...

This does not say what goes into the field. It also does not explain why it makes unique emails collide by lowercasing them. Please document this field, as a start in documenting the entire feature.

Thanks!

[johnnyaug]

Removed this ambiguity in: #3703